﻿<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../helpproject.xsl" ?>
<topic template="Default" lasteditedby="Geert" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../helpproject.xsd">
  <title translate="true">Exception handling</title>
  <keywords>
    <keyword translate="true">Exception</keyword>
    <keyword translate="true">Exception handling</keyword>
    <keyword translate="true">ExceptionHandler</keyword>
    <keyword translate="true">Exceptions</keyword>
    <keyword translate="true">ExceptionService</keyword>
    <keyword translate="true">IExceptionHandler</keyword>
    <keyword translate="true">IExceptionService</keyword>
  </keywords>
  <body>
    <header>
      <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Exception handling</text></para>
    </header>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">With exception handling in Catel, it is possible to create an exception handling policy and execute code in a safe way without have to check all the exception types manually.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Catel exposes this technique via the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_ExceptionHandling_IExceptionService" styleclass="Normal" translate="true">IExceptionService</link><text styleclass="Normal" translate="true">.</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Setting up the IExceptionService</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">It is important to register an exception in the service and let Catel know how it should be handled. The service handles exceptions in the way they are added to the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_ExceptionHandling_IExceptionService" styleclass="Normal" translate="true">IExceptionService</link><text styleclass="Normal" translate="true">.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The example below registers several exceptions and how they should be handled. When a </text><text styleclass="Normal" style="font-style:italic;" translate="true">FileNotFoundException </text><text styleclass="Normal" style="font-style:normal; text-decoration:none;" translate="true">occurs, it will show a message to the user. For any other exception, it will log the exception and show a message that the user should contact the developers.</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">exceptionService</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">GetService&lt;IExceptionService&gt;();</text><br/><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">exceptionService.Register&lt;FileNotFoundException&gt;(exception</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">=&gt;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">GetService&lt;IMessageService&gt;().Show(exception.Message));</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">exceptionService.Register&lt;Exception&gt;(exception</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">=&gt;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">    Log.Error(exception);</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">    GetService&lt;IMessageService&gt;().Show(&quot;An unknown exception occurred, please contact the developers&quot;);</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">});</text></para>
    <para styleclass="Notes"><text styleclass="Notes" translate="true">The IExceptionService checks for type hierarchy. For example, when an exception as type Exception</text><text styleclass="Notes" translate="true"> is registered, this handler will handle all exceptions</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Executing code using the IExceptionService</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_ExceptionHandling_IExceptionService_Process_1_62c6d5e6" styleclass="Normal" translate="true">Process</link><text styleclass="Normal" translate="true"> method is responsible to keep track of all exceptions which might occur and will handle them if they are registered. If one of your registered exceptions is thrown by the code, the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_ExceptionHandling_IExceptionService_Process_1_62c6d5e6" styleclass="Normal" translate="true">Process</link><text styleclass="Normal" translate="true"> method will handle it and perform the action defined while the registration operation (for example, by showing a message box).</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_ExceptionHandling_IExceptionService_Process_1_62c6d5e6" styleclass="Normal" translate="true">Process</link><text styleclass="Normal" translate="true"> method comes in two flavors: as action and as function.</text></para>
    <para styleclass="Heading2"><text styleclass="Heading2" translate="true">Executing an action</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">exceptionService</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">GetService&lt;IExceptionService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">exceptionService.Process(()</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">=&gt;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">{</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; text-decoration:none; color:#000000;" translate="true">throw</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; text-decoration:none; color:#000000;" translate="true">new</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">ArgumentOutOfRangeException();</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">});</text></para>
    <para styleclass="Heading2"><text styleclass="Heading2" translate="true">Executing a function</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">exceptionService</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">GetService&lt;IExceptionService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">result</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">exceptionService.Process&lt;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; text-decoration:none; color:#000000;" translate="true">int</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">&gt;(()</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">=&gt;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">1</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">+</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">1);</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Handling exceptions manually</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">It is possible to manually handle exceptions using the service. This is useful when you don&apos;t want to wrap code in the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_ExceptionHandling_IExceptionService_Process_1_62c6d5e6" styleclass="Normal" translate="true">Process</link><text styleclass="Normal" translate="true"> method, but still want to be able to create a generic exception handling policy.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">var exceptionService = GetService&lt;IExceptionService&gt;();</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:bold; font-style:normal; text-decoration:none; color:#000000;" translate="true">try</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">    var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">value</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">150/0;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">}</text><br/><text styleclass="Code Example" style="font-weight:bold; font-style:normal; text-decoration:none; color:#000000;" translate="true">catch</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">(DivideByZeroException</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">exception)</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">    exceptionService.HandleException(exception);</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">}</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">If the exception can be handled, the registered action will be executed, but your code can safely continue. If the exception (in this case </text><text styleclass="Normal" style="font-style:italic;" translate="true">DivideByZeroException</text><text styleclass="Normal" style="font-style:normal;" translate="true">) is not registered, the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_ExceptionHandling_IExceptionService_HandleException_1_2ffb7699" styleclass="Normal" style="font-style:normal;" translate="true">HandleException</link><text styleclass="Normal" style="font-style:normal;" translate="true"> method will rethrow the exception.</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Unregistering exceptions</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Although it will probably hardly used, it is possible to unregister exceptions again using the code below:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">exceptionService</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">GetService&lt;IExceptionService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; text-decoration:none; color:#000000;" translate="true">exceptionService.Unregister&lt;ArgumentException&gt;();</text></para>
  </body>
</topic>
